Inside Macintosh: Programming With JManager /

Chapter 1 - Using JManager

Finding Applets

Before you can instantiate and execute your applet, you must find the applet code by creating a JMAppletLocatorRef object. You can create such an object either synchronously or asynchronously. A synchronous search assumes that the applet's location can be immediately verified (if, for example, it is contained in a local file). You use the JMNewAppletLocatorFromInfo function for a synchronous search, and you must provide information about the location of the applet in a JMLocatorInfoBlock data structure. The location information is the same as you would find in an applet tag in an HTML document. Listing 1-4 shows an example of using JMNewAppletLocatorFromInfo.

Listing 1-4 Using the JMNewAppletLocatorFromInfo function

OSStatus err = noErr;
JMAppletLocatorRef locatorRef;
JMTextRef URLTextRef, appTextRef;

/* Build the text objects for the strings to pass */ 
JMNewTextRef (theSession, &URLTextRef, kTextEncodingMacRoman,
            "file:///$APPLICATION/applets/DrawTest/example1.html",
            51);

JMNewTextRef (theSession, &appTextRef, /* from the applet tag */
            kTextEncodingMacRoman,"DrawTest.class",14);

JMLocatorInfoBlock infoBlock = {
   kJMVersion,                   /* should be kJMVersion */
   URLTextRef,
   appTextRef,
   400, 400,                     /* width, height */
   0, nil         /* no optional parameters in this example */
};

/* create the locator */ 
/* If noErr is returned, the infoBlock was valid */
err =  JMNewAppletLocatorFromInfo(&locatorRef, 
      theSession, &infoBlock, 0);

if (err == noErr) {
   /* instantiate and execute applet */
   }

/* Dispose text objects after use */
JMDisposeTextRef(URLTextRef); 
JMDisposeTextRef(appTextRef); 

Note that the two strings passed in the information block (the URL and the name of the class containing the applet code) are passed as text objects.

The /$APPLICATION/ indicator in the URL is an Apple-specific designation that indicates the current application directory.

For more information about the JMLocatorInfoBlock structure, see "The Applet Locator Information Block".

If the applet is located on a remote server, you should search for it asynchronously using the JMNewAppletLocator function . Listing 1-5 shows an example of using JMNewAppletLocator.

Listing 1-5 Using the JMNewAppletLocator function

JMAppletLocatorRef locatorRef;
JMTextRef sampleURLTextRef;

struct JMAppletLocatorCallbacks locatorCallbacks = {
   kJMVersion,    /* should be kJMVersion */
   MyFetchCompleted/* called on completion */
   };

JMNewTextRef (theSession, &sampleURLTextRef, kTextEncodingMacRoman, 
            "http://www.hypno.com/javabeta/bongo/bongo.html", 46);

/* ignore the result--no pointer is passed to the */
/* html text, since it might not exist locally.*/
(void) JMNewAppletLocator(&locatorRef, theSession,
         &locatorCallbacks, sampleURLTextRef, nil, 0);

JMDisposeTextRef(sampleURLTextRef); /* dispose text object after use */
JMIdle(theSession, kDefaultJMTime);

/* this is the callback function specified in locatorCallbacks */
static void MyFetchCompleted(JMAppletLocatorRef locatorRef,
      JMLocatorErrors status){
   if (status != eLocatorNoErr) {
      /* handle the error here--perhaps put up a dialog box */
      } 
   else {
      /* instantiate and execute applet */
      }
}

In the asynchronous search, you pass HTML text (as a text object) indicating the location of the applet and specify a callback function to execute when the search is completed. The callback function can take various actions, depending on the status value returned. For more information about the callback function, see MyFetchCompleted .

IMPORTANT

It is possible that the MyFetchCompleted function will be called before JMNewAppletLocator returns.

One you have found your applet's location, you should call the JMCountApplets function to determine the number of applets associated with the HTML page. JMCountApplets counts the number of applets and assigns an index value to each. Then you can use the functions JMGetAppletDimensions, JMGetAppletTag, and JMGetAppletName to determine which applet to instantiate or to get more information about a particular applet. Listing 1-6 shows an example that counts the number of applets and returns information about each.

Listing 1-6 Retrieving information from an applet's HTML page

UInt32 appletCount;
UInt32 appWidth, appHeight;
UInt32 i;
JMTextRef appNameTextRef;
Handle appName;

/* iterate over the applets */
err = JMCountApplets(locatorRef, &appletCount);
printf("Number of Applets: "appletCount);

for (i = 0;  i < appletCount && err == noErr;  i++) {
   err = JMGetAppletName( locatorRef, i, &appNameTextRef);

   appName = JMTextToMacOSCStringHandle(appNameTextRef);
   Hlock(appName);

   if (!err) {
      err = JMGetAppletDimensions(locatorRef, i, &appWidth,
            &appHeight);
      if (!err) {
         printf("\nApplet #"%d" is "%s,i+1,*appName); 
         printf("Dimensions:"%d" by "%d" pixels",appWidth,appHeight);
         }
      }
   HUnlock(appName);
   }
DisposeHandle(appName);

In some cases you might want to associate some client-specific data with an applet locator. To do so you can use the functions JMGetAppletLocatorData and JMSetAppletLocatorData.

Both the JMNewAppletLocatorFromInfo and JMNewAppletLocator functions provide a valid JMLocatorRef object, which you can then use to instantiate and execute the applet. After instantiating the applet, however, you no longer need the JMLocatorRef object, so you can remove it by calling the JMDisposeAppletLocator function.